From dd2459cd2f6aa2e8a70736372b3ed5420c82eae7 Mon Sep 17 00:00:00 2001
From: Christoph Burgdorf <christoph.burgdorf@bvsn.org>
Date: Sat, 12 Jul 2014 20:54:31 +0200
Subject: [PATCH] Add documentation and make minor variable renames

---
 src/cargo/ops/cargo_clean.rs | 13 +++++++++----
 src/cargo/util/toml.rs       | 21 ++++++++++++++-------
 2 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/src/cargo/ops/cargo_clean.rs b/src/cargo/ops/cargo_clean.rs
index 2d6788594..a9aab85d6 100644
--- a/src/cargo/ops/cargo_clean.rs
+++ b/src/cargo/ops/cargo_clean.rs
@@ -5,12 +5,17 @@ use ops::{read_manifest};
 use std::io::{File};
 use util::toml::{project_layout};
 
-pub fn clean(path: &Path) -> CargoResult<()>
+/// Cleans the project from build artifacts.
+
+pub fn clean(manifest_path: &Path) -> CargoResult<()>
 {
-    let mut file = try!(File::open(path));
+    let mut file = try!(File::open(manifest_path));
     let data = try!(file.read_to_end());
-    let layout = project_layout(&path.dir_path());
-    let (manifest, _) = try!(read_manifest(data.as_slice(), layout, &SourceId::for_path(path)));
+    let layout = project_layout(&manifest_path.dir_path());
+    let (manifest, _) = try!(read_manifest(data.as_slice(), 
+                                           layout, 
+                                           &SourceId::for_path(manifest_path)));
+
     let build_dir = manifest.get_target_dir();
 
     if build_dir.exists() {
diff --git a/src/cargo/util/toml.rs b/src/cargo/util/toml.rs
index ffed1d2e0..85b525537 100644
--- a/src/cargo/util/toml.rs
+++ b/src/cargo/util/toml.rs
@@ -11,6 +11,10 @@ use core::package_id::Metadata;
 use core::source::Location;
 use util::{CargoResult, Require, human};
 
+/// Representation of the projects file layout.
+///
+/// This structure is used to hold references to all project files that are relevant to cargo.
+
 #[deriving(Clone)]
 pub struct Layout {
     lib: Option<Path>,
@@ -45,22 +49,25 @@ fn try_add_files(files: &mut Vec<Path>, root: &Path, dir: &str) {
     }
 }
 
-pub fn project_layout(root: &Path) -> Layout {
+/// Returns a new `Layout` for a given root path.
+/// The `root_path` represents the directory that contains the `Cargo.toml` file.
+
+pub fn project_layout(root_path: &Path) -> Layout {
     let mut lib = None;
     let mut bins = vec!();
     let mut examples = vec!();
     let mut tests = vec!();
 
-    if root.join("src/lib.rs").exists() {
-        lib = Some(root.join("src/lib.rs"));
+    if root_path.join("src/lib.rs").exists() {
+        lib = Some(root_path.join("src/lib.rs"));
     }
 
-    try_add_file(&mut bins, root, "src/main.rs");
-    try_add_files(&mut bins, root, "src/bin");
+    try_add_file(&mut bins, root_path, "src/main.rs");
+    try_add_files(&mut bins, root_path, "src/bin");
 
-    try_add_files(&mut examples, root, "examples");
+    try_add_files(&mut examples, root_path, "examples");
 
-    try_add_files(&mut tests, root, "tests");
+    try_add_files(&mut tests, root_path, "tests");
 
     Layout {
         lib: lib,
-- 
2.30.2